REST API's

Pyramid includes a robust library of API functions to allow customers to programmatically access and manage the application. The API's are exposed through REST and can be used from almost any programming environment that supports standard REST calls.

Versions

The REST API's come in 2 versions.

• Version 1.0 (up to 2018.04) covers core functionality - but has been deprecated. It is still included for backwards compatibility.
• Version 2.0 (from 2018.05 onwards) covers the same functionality but has been simplified and extended.

For long term stability and support, developers should be working off the 2.0 version.

REST API Approach and Structure

Get vs POST

Classic REST APIs typically use GET templates to drive functionality. However, this approach is best suited for simplistic functions and is inherently weak when there are multiple method parameters (which is usually too long for GET URLs) and if the parameter objects are richer with multiple (nested) property options and settings.

Security

The limitations of the GET approach are further compounded by the security authorization mechanics needed to govern access to a system like Pyramid. All API actions in Pyramid need to have an authorization token to ensure the right user can perform the right action. Using the GET approach, the authorization token would need to be passed by Cookie or HTTP header - which is an added complication for developers working outside of languages like JavaScript.

 

As such, Pyramid's API is modeled on a "POST" model, where JSON data objects are posted in the API method calls facilitating the larger, more complex nested objects (in JSON). They also allow a much simpler and direct method of authorizing each method call using security tokens. Pyramid APIs are still executed via an URL model, using the same HTTP protocols and responses, with the method name driving the URL as per standard GET.

Method Verbs

The more standardized approach to REST uses classic verb structures (Add / Edit / Delete etc) for different objects. Since the objects in Pyramid contain a significant number of properties and there are complexities around security and API operation, Pyramid has decided on a "direct method" approach to the API methods instead to simplify implementation of the API and associated activities.

Function List

The REST API functions cover a variety of core functions, covering authentication and access, administration and content operations. Where relevant, objects needed to implement these functions are described in a separate definitions list.

API 2.0

• Authentication Index - logging into the application programmatically
• Access Index - security and system access operations
• Content Index - content management and operations
• Query Index - query execution
• Data Sources Index - data source management and operations
• Tasks Index - task operations
• Notifications Index - notification details

API 1.0 (deprecated)

• Authentication Index
• Operations Index
• Administration Index
• Query Index

Object Definitions for both API Versions

• Object Definitions Index - all objects and classes used in the API calls and responses.

API Response Status

When an API is called a status of the call is usually given withing the response. The API documentation highlights the response of successful calls. The list of all statuses and their associated status codes, including unsuccessful calls, is provided here.

Examples

Examples are provided throughout the documentation covering a variety of the methods in the API. The methods with examples are highlighted on the main section ('namespace') pages above.